MV_CC_GetOneFrameTimeout

MV_CC_GetOneFrameTimeout

Get one frame of picture, support getting chunk information and setting timeout.

API Definition

int MV_CC_GetOneFrameTimeout(
  void                    *handle,
  unsigned char           *pData,
  unsigned int            nDataSize,
  MV_FRAME_OUT_INFO_EX    *pFrameInfo,
  unsigned int            nMsec
);

Parameters

handle

[IN] Device handle, which is returned by MV_CC_CreateHandle or MV_CC_CreateHandleWithoutLog.

pData

[IN] Buffer address used to save image data

nDataSize

[IN] Buffer size

pFrameInfo

[OUT] Obtained frame information, including chunk information, see the structure MV_FRAME_OUT_INFO_EX for details.

nMsec

[IN] Waiting timeout, unit: millisecond

Return Value

Return MV_OK(0) on success, and return Error Code on failure.

Remarks

  • Before calling this API to get image data frame, call MV_CC_StartGrabbing to start image acquisition. This API can get frame data actively, the upper layer program should control the frequency of calling this API according to the frame rate. This API supports setting timeout, SDK will wait to return until data appears. This function will increase the streaming stability, which can be used in the situation with high stability requirement.

  • This API is supported by both the USB3Vision and GIGE camera.

  • This API is not supported by CameraLink device.

The following sample code is for reference only.

#include "MvCameraControl.h"

void main()
{
    int nRet = -1;
    void* m_handle = NULL;

    //Enumerate all the corresponding devices of specified transport protocol in the subnet.
    unsigned int nTLayerType = MV_GIGE_DEVICE | MV_USB_DEVICE;
    MV_CC_DEVICE_INFO_LIST m_stDevList = {0};
    int nRet = MV_CC_EnumDevices(nTLayerType, &m_stDevList);
    if (MV_OK != nRet)
    {
        printf("error: EnumDevices fail [%x]\n", nRet);
        return;
    }

    int i = 0;
    if (m_stDevList.nDeviceNum == 0)
    {
        printf("no camera found!\n");
        return;
    }

    //Selected the first online device in the search result, and create device handle.
    int nDeviceIndex = 0;

    MV_CC_DEVICE_INFO m_stDevInfo = {0};
    memcpy(&m_stDevInfo, m_stDevList.pDeviceInfo[nDeviceIndex], sizeof(MV_CC_DEVICE_INFO));

    nRet = MV_CC_CreateHandle(&m_handle, &m_stDevInfo);

    if (MV_OK != nRet)
    {
        printf("error: CreateHandle fail [%x]\n", nRet);
        return;
    }

    //Connect to device
    nRet = MV_CC_OpenDevice(m_handle, nAccessMode, nSwitchoverKey);
    if (MV_OK != nRet)
    {
        printf("error: OpenDevice fail [%x]\n", nRet);
        return;
    }
    //...Other processes

    //Start image acquisition
    nRet = MV_CC_StartGrabbing(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: StartGrabbing fail [%x]\n", nRet);
        return;
    }

    //Get the size of one frame data
    MVCC_INTVALUE stIntvalue = {0};
    nRet = MV_CC_GetIntValue(m_handle, "PayloadSize", &stIntvalue);
    if (nRet != MV_OK)
    {
        printf("Get PayloadSize failed! nRet [%x]\n", nRet);
        return;
    }
    int nBufSize = stIntvalue.nCurValue + 2048; //One frame data size + reserved bytes (handled in SDK)

    unsigned int    nTestFrameSize = 0;
    unsigned char*  pFrameBuf = NULL;
    pFrameBuf = (unsigned char*)malloc(nBufSize);

    MV_FRAME_OUT_INFO_EX stInfo;
    memset(&stInfo, 0, sizeof(MV_FRAME_OUT_INFO_EX));

    //The upper layer program should control the frequency of calling  this API according to the frame rate.
    //The codes is for reference only, please establish another thread to execute image acquisition and handling in actual application.
    while(1)
    {
        if (nTestFrameSize > 99) 
        {
            break;
        }
        nRet = MV_CC_GetOneFrameTimeout(m_handle, pFrameBuf, nBufSize, &stInfo, 1000);
        if (MV_OK != nRet)
        {
            Sleep(10);
        }
        else
        {
            //...Processing image data
            nTestFrameSize++;
        }
    }

    //...Other processes

    //Stop image acquisition
    nRet = MV_CC_StopGrabbing(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: StopGrabbing fail [%x]\n", nRet);
        return;
    }

    //Close device, release resource.
    nRet = MV_CC_CloseDevice(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: CloseDevice fail [%x]\n", nRet);
        return;
    }

    //Destroy handle, release resource
    nRet = MV_CC_DestroyHandle(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: DestroyHandle fail [%x]\n", nRet);
        return;
    }    
}

MV_CC_GetOneFrameTimeout

Get one frame of picture, support getting chunk information and setting timeout.

API Definition

int MV_CC_GetOneFrameTimeout(
  void                    *handle,
  unsigned char           *pData,
  unsigned int            nDataSize,
  MV_FRAME_OUT_INFO_EX    *pFrameInfo,
  unsigned int            nMsec
);

Parameters

handle

[IN] Device handle, which is returned by MV_CC_CreateHandle or MV_CC_CreateHandleWithoutLog.

pData

[IN] Buffer address used to save image data

nDataSize

[IN] Buffer size

pFrameInfo

[OUT] Obtained frame information, including chunk information, see the structure MV_FRAME_OUT_INFO_EX for details.

nMsec

[IN] Waiting timeout, unit: millisecond

Return Value

Return MV_OK(0) on success, and return Error Code on failure.

Remarks

  • Before calling this API to get image data frame, call MV_CC_StartGrabbing to start image acquisition. This API can get frame data actively, the upper layer program should control the frequency of calling this API according to the frame rate. This API supports setting timeout, SDK will wait to return until data appears. This function will increase the streaming stability, which can be used in the situation with high stability requirement.

  • This API is supported by both the USB3Vision and GIGE camera.

  • This API is not supported by CameraLink device.

The following sample code is for reference only.

#include "MvCameraControl.h"

void main()
{
    int nRet = -1;
    void* m_handle = NULL;

    //Enumerate all the corresponding devices of specified transport protocol in the subnet.
    unsigned int nTLayerType = MV_GIGE_DEVICE | MV_USB_DEVICE;
    MV_CC_DEVICE_INFO_LIST m_stDevList = {0};
    int nRet = MV_CC_EnumDevices(nTLayerType, &m_stDevList);
    if (MV_OK != nRet)
    {
        printf("error: EnumDevices fail [%x]\n", nRet);
        return;
    }

    int i = 0;
    if (m_stDevList.nDeviceNum == 0)
    {
        printf("no camera found!\n");
        return;
    }

    //Selected the first online device in the search result, and create device handle.
    int nDeviceIndex = 0;

    MV_CC_DEVICE_INFO m_stDevInfo = {0};
    memcpy(&m_stDevInfo, m_stDevList.pDeviceInfo[nDeviceIndex], sizeof(MV_CC_DEVICE_INFO));

    nRet = MV_CC_CreateHandle(&m_handle, &m_stDevInfo);

    if (MV_OK != nRet)
    {
        printf("error: CreateHandle fail [%x]\n", nRet);
        return;
    }

    //Connect to device
    nRet = MV_CC_OpenDevice(m_handle, nAccessMode, nSwitchoverKey);
    if (MV_OK != nRet)
    {
        printf("error: OpenDevice fail [%x]\n", nRet);
        return;
    }
    //...Other processes

    //Start image acquisition
    nRet = MV_CC_StartGrabbing(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: StartGrabbing fail [%x]\n", nRet);
        return;
    }

    //Get the size of one frame data
    MVCC_INTVALUE stIntvalue = {0};
    nRet = MV_CC_GetIntValue(m_handle, "PayloadSize", &stIntvalue);
    if (nRet != MV_OK)
    {
        printf("Get PayloadSize failed! nRet [%x]\n", nRet);
        return;
    }
    int nBufSize = stIntvalue.nCurValue + 2048; //One frame data size + reserved bytes (handled in SDK)

    unsigned int    nTestFrameSize = 0;
    unsigned char*  pFrameBuf = NULL;
    pFrameBuf = (unsigned char*)malloc(nBufSize);

    MV_FRAME_OUT_INFO_EX stInfo;
    memset(&stInfo, 0, sizeof(MV_FRAME_OUT_INFO_EX));

    //The upper layer program should control the frequency of calling  this API according to the frame rate.
    //The codes is for reference only, please establish another thread to execute image acquisition and handling in actual application.
    while(1)
    {
        if (nTestFrameSize > 99) 
        {
            break;
        }
        nRet = MV_CC_GetOneFrameTimeout(m_handle, pFrameBuf, nBufSize, &stInfo, 1000);
        if (MV_OK != nRet)
        {
            Sleep(10);
        }
        else
        {
            //...Processing image data
            nTestFrameSize++;
        }
    }

    //...Other processes

    //Stop image acquisition
    nRet = MV_CC_StopGrabbing(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: StopGrabbing fail [%x]\n", nRet);
        return;
    }

    //Close device, release resource.
    nRet = MV_CC_CloseDevice(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: CloseDevice fail [%x]\n", nRet);
        return;
    }

    //Destroy handle, release resource
    nRet = MV_CC_DestroyHandle(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: DestroyHandle fail [%x]\n", nRet);
        return;
    }    
}